/*
 * This program is free software: you can redistribute it and/or modify it under
 * the terms of the GNU General Public License as published by the Free Software
 * Foundation, either version 3 of the License, or (at your option) any later
 * version.
 *
 * This program is distributed in the hope that it will be useful, but WITHOUT
 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
 * FOR A PARTICULAR PURPOSE. See the GNU General Public License for more
 * details.
 *
 * You should have received a copy of the GNU General Public License along with
 * this program. If not, see <http://www.gnu.org/licenses/>.
 */
package net.sf.l2j.gameserver.ai;

import net.sf.l2j.gameserver.model.L2Character;

/**
 * Interface of AI and client state. To correctly send messages to client we
 * need it's state. For example, if we've sent 'StartAutoAttack' message, we
 * need to send 'StopAutoAttack' message before any other action. Or if we've
 * sent 'MoveToPawn', we need to send 'StopMove' when the movement of a
 * character is canceled (by Root spell or any other reason). Thus, we need to
 * know the state of client, i.e. which messages we've sent and how the client
 * will show the scene. Close to this task is the task of AI. If a player's
 * character is attacking a mob, his ATTACK may be iterrupted by an event, that
 * temporary disable attacking. But when the possibility to ATTACK will be
 * enabled, the character must continue the ATTACK. For mobs it may be more
 * complex, since we want them to decide when to use magic, or when to follow
 * the player for physical combat, or when to escape, to help another mob, etc.
 * This interface is hiding complexity of server<->client interaction and
 * multiple states of a character. It allows to set a desired, simple "wish" of
 * a character, and the implementation of this interface will take care about
 * the rest. The goal of a character may be like "ATTACK", "random walk" and so
 * on. To reach the goal inplementation will split it into several small
 * actions, several steps (possibly repeatable). Like "run to target" then
 * "hit it", then if target is not dead - repeat. This flow of simplier steps
 * may be interrupted by incoming events. Like a character's movement was
 * disabled (by Root spell, for instance). Depending on character's ability AI
 * may choose to wait, or to use magic ATTACK and so on. Additionally incoming
 * events are compared with client's state of the character, and required
 * network messages are sent to client's, i.e. if we have incoming event that
 * character's movement was disabled, it causes changing if its behavour, and if
 * client's state for the character is "moving" we send messages to clients to
 * stop the avatar/mob.
 */
public interface Ctrl {
	/** the character this AI serves */
	L2Character getActor();

	/** get current intention */
	CtrlIntention getIntention();

	/** get current ATTACK target */
	L2Character getAttackTarget();

	/** Set general state/intention for AI, with optional data */
	void setIntention(CtrlIntention intention);

	void setIntention(CtrlIntention intention, Object arg0);

	void setIntention(CtrlIntention intention, Object arg0, Object arg1);

	/**
	 * Event, that notifies about previous step result, or user command, that
	 * does not change current general intention
	 */
	void notifyEvent(CtrlEvent evt);

	void notifyEvent(CtrlEvent evt, Object arg0);

	void notifyEvent(CtrlEvent evt, Object arg0, Object arg1);
}
